数据服务

数据管理DMS的数据服务是将您在DMS上管控的数据以API的形式快速对外输出的功能,本文将介绍如何新增、发布、测试与调用API。

前提条件

已开通API网关

准备工作

本示例已提前创建student_courses表,并插入部分测试数据,SQL语句如下:

/** 创建表 **/
CREATE TABLE `student_courses` (
  `id` BIGINT(20) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
  `student_id` BIGINT(20) DEFAULT NULL COMMENT '学生ID',
  `course_id` BIGINT(20) DEFAULT NULL COMMENT '课程ID',
  `start_time` DATETIME DEFAULT NULL COMMENT '创建时间',
  `score` int(11) DEFAULT NULL COMMENT '考试成绩',
  KEY `idx_student_course` (`student_id`,`course_id`),
  KEY `idx_student_time` (`student_id`,`start_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='数据服务测试表';

/** 插入数据 **/
INSERT INTO `student_courses` VALUES (1,1,1,'2020-11-24 11:19:54',78);
INSERT INTO `student_courses` VALUES (2,1,2,'2020-11-24 05:51:36',68);
INSERT INTO `student_courses` VALUES (3,1,3,'2020-11-24 05:28:08',60);
INSERT INTO `student_courses` VALUES (4,2,1,'2020-11-24 07:21:17',67);
INSERT INTO `student_courses` VALUES (5,2,2,'2020-11-24 02:07:52',91);
INSERT INTO `student_courses` VALUES (6,2,3,'2020-11-24 10:35:35',94);
INSERT INTO `student_courses` VALUES (7,3,1,'2020-11-24 03:19:03',53);
INSERT INTO `student_courses` VALUES (8,3,2,'2020-11-24 08:19:18',94);
INSERT INTO `student_courses` VALUES (9,3,3,'2020-11-24 02:04:17',89);

步骤一:新增并发布API

  1. 登录数据管理DMS 5.0
  2. 在顶部菜单栏中,选择集成与开发(DTS) > 数据应用 > 数据服务

    说明

    若您使用的是极简模式的控制台,请单击控制台左上角的2023-01-28_15-57-17.png图标,选择全部功能 > 集成与开发(DTS) > 数据应用 > 数据服务

  3. 进入数据服务页面后,在左侧导航栏,单击API开发

  4. 进入API管理页面,单击右上角的新增API

  5. 配置信息。

    API的属性包含属性配置执行配置请求参数返回参数,共4个部分,由于配置信息较多,系统用4个页签展示。本示例仅介绍部分涉及到的参数,完整的参数说明,请参见管理API

    • 属性配置

      名词

      名词解释

      API名称(必选)

      数据API的名称,支持汉字,英文,数字,下划线(_),且只能以英文和汉字开头,4~100个字符。

      本示例的API名称为POC_API_test

      路径(必选)

      该路径为API调用地址的组成部分。

      路径只能以/开头,只支持英文、数字、下划线(_)、横杠(-),如/item/add

      API调用地址的结构为:https://{分组域名}{路径}

      如本示例的路径定义为/item/POC_API_test、分组域名为xxxx-cn-hangzhou.alicloudapi.com,则最终API调用地址为https://xxxx-cn-hangzhou.alicloudapi.com/item/POC_API_test

      请求方式(必选)

      通用的API请求方式,支持的选项:

      • POST

      • GET

      本示例的请求方式为GET

      属性配置_poc_API_test

    • 执行配置

      本示例的执行配置单实例查询表引导模式,并设置student_id字段为请求参数,student_idcourse_idscore字段为返回参数。

      名词

      名词解释

      实例查询类型

      实例查询的类型,支持的权限:

      • 单实例查询:仅查询一个数据库实例。可以通过表引导模式和SQL脚本模式定义API。

      • 跨实例查询:通过编写跨数据库查询DSQL,来实现多个不同实例数据的关联查询,详细信息,请参见官方文档。仅支持SQL脚本模式定义API。

      数据源

      待查询的数据库。通过输入关键字,可查询当前用户有查询权限的数据库。

      该参数仅当实例查询类型单实例查询模式时显示。

      配置方式

      选择API的配置方式,支持的选项:

      • 表引导模式:通过可视化的方式选择表、字段,定义API的数据查询配置。

      • 脚本模式:通过手动编写SQL脚本+变量的方式来定义API的数据查询配置。

      说明

      表引导模式切换为脚本模式时,系统将提示切换模式将清空请求参数和返回参数。

      该参数仅当实例查询类型单实例查询模式时显示。

      选择表

      表引导模式下,可选择需要执行查询的表。可通过输入关键字快捷查找表。

      该参数仅当配置方式表引导模式时显示。

      字段列表

      该字段列表会展示当前选择的数据表中的所有字段,您可以通过勾选的方式,快速定义目标字段作为API的请求参数和返回参数。

      该参数仅当配置方式表引导模式时显示。

      配置执行方式POC_api_test

    • 请求参数

      名词

      名词解释

      参数名称

      调用API时的入参名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。

      变量名称字段名称

      这里显示该参数来源,可来源于表引导模式的字段,也可来源于脚本模式的变量。

      数据类型

      包括字符串整型浮点三种基本类型,默认为字符串。本示例将student_id参数的数据类型设置为整型

      此参数的作用为:在调用时将校验请求参数值是否符合对应的类型,且在执行API时,保障SQL的正常执行。

      请求参数

    • 返回参数

      名词

      名词解释

      参数名称

      返回参数名称,支持英文、数字、横杠(-)、下划线(_),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。

      变量名称字段名称

      仅显示返回的字段名。

      数据类型

      包括字符串整型浮点三种基本类型,默认为字符串

      此参数的作用为:系统把查询后的数据,按照此处定义进行数据转换,最终将数据写入返回的JSON中。

      返回参数

  6. 配置完成后,单击发布按钮。

    说明

    您也可以单击保存按钮,保存该API的配置。

    至此,已发布该API接口。

步骤二:测试API

验证API配置是否正确。

  1. 登录数据管理DMS 5.0
  2. 在顶部菜单栏中,选择集成与开发(DTS) > 数据应用 > 数据服务

    说明

    若您使用的是极简模式的控制台,请单击控制台左上角的2023-01-28_15-57-17.png图标,选择全部功能 > 集成与开发(DTS) > 数据应用 > 数据服务

  3. 在左侧导航栏,单击API测试

  4. 在下拉框中,选择POC_API_test

  5. 参数值文本框中。输入1,单击测试按钮。

    执行后,右侧会显示执行信息以及执行的返回结果(以表格和JSON两种方式呈现)。测试API返回结果

步骤三:调用API

您可以通过多种方式调用API,例如使用SDK调用API和客户端调用API,调用时认证方式包括简单认证(AppCode)和摘要签名认证方式。具体操作,请参见API调用概述

本示例介绍使用简单认证(AppCode)方式调用API。API调用地址的结构为:https://{Endpoint}{API路径}?AppCode=AppCode值&请求参数1=xxx&请求参数2=xxx。您可以在DMS控制台上获取EndpointAppCode值等信息。

  1. 登录数据管理DMS 5.0
  2. 在顶部菜单栏中,选择集成与开发(DTS) > 数据应用 > 数据服务

    说明

    若您使用的是极简模式的控制台,请单击控制台左上角的2023-01-28_15-57-17.png图标,选择全部功能 > 集成与开发(DTS) > 数据应用 > 数据服务

  3. 在左侧导航栏,单击API调用

  4. API调用页面,获取Endpoint与AppCode值。

    本示例的API调用地址为:https://xxxe3e-cn-hangzhou.alicloudapi.com/item/POC_API_test?AppCode=3284xxxxx&student_id=1

    image

    您可以将API调用地址复制到浏览器或通过curl命令调用该API。